Events registration

What is the custom event?

A Custom event is any kind of event integrated with the Insights Factory System, which Insight Definitions could be assigned to.

As a result, the system could react to the occurrence of this event by sending a customized Insight message to a relevant audience when Triggering conditions are met.

For more details on used metadata please refer to Domain Language Glossary Section.

How to integrate the custom event?

Integration of the Custom event with the Insights Factory System could be done with a few simple steps:

event schema registration
defining Custom types (optional)
Event metadata adjustment (optional)

note

Full API specification for integrating Custom Events can be found in Insights Factory Events Integration API .

Step 1: Event schema registration

Registering event schema could be done via endpoint

POST /integration/insights/v1/events
curl --request POST '/integration/insights/v1/events' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "eventTypeIdentifier": "CarbonInsightCreated",
  "name": "Carbon Insight",
  "description": "",
  "fields": {
    "UserIdentifier": "string",
    "TenantIdentifier": "string",
    "Identifier": "string",
    "ParentIdentifier": "string",
    "AccountIdentifier": "string",
    "TransactionDateTime": "dateTime",
    "CarbonGrams": "double",
    "CategoryId": "int",
    "InsertedDate": "dateTime",
    "Amount": "decimal",
    "Currency": "string",
    "SourceAccount": "Account"
  },
  "subTypes": [
    {
      "name": "Account",
      "fields": {
        "AccountIdentifier": "string",
        "AccountType": "int"
      }
    }
  ]
}'

201 Created
{
  "data": {
    "eventTypeIdentifier": "CarbonInsightCreated",
    "name": "Carbon Insight",
    "description": "",
    "isAvailable": true,
    "fields": {
      "UserIdentifier": {
        "label": "UserIdentifier",
        "type": "text",
        "tooltip": null,
        "disabled": true
      },
      "TenantIdentifier": {
        "label": "TenantIdentifier",
        "type": "text",
        "tooltip": null,
        "disabled": true
      },
      "Identifier": {
        "label": "Identifier",
        "type": "text",
        "tooltip": null,
        "disabled": true
      },
      "ParentIdentifier": {
        "label": "ParentIdentifier",
        "type": "text",
        "tooltip": null,
        "disabled": true
      },
      "AccountIdentifier": {
        "label": "AccountIdentifier",
        "type": "text",
        "tooltip": null,
        "disabled": true
      },
      "TransactionDateTime": {
        "label": "TransactionDateTime",
        "type": "datetime",
        "tooltip": null,
        "disabled": true
      },
      "CarbonGrams": {
        "label": "CarbonGrams",
        "type": "number",
        "tooltip": null,
        "disabled": true
      },
      "CategoryId": {
        "label": "CategoryId",
        "type": "number",
        "tooltip": null,
        "disabled": true
      },
      "InsertedDate": {
        "label": "InsertedDate",
        "type": "datetime",
        "tooltip": null,
        "disabled": true
      },
      "Amount": {
        "label": "Amount",
        "type": "number",
        "tooltip": null,
        "disabled": true
      },
      "Currency": {
        "label": "Currency",
        "type": "text",
        "tooltip": null,
        "disabled": true
      },
      "SourceAccount": {
        "label": "SourceAccount",
        "type": "!struct",
        "subfields": {
          "AccountIdentifier": {
            "label": "SourceAccount.AccountIdentifier",
            "type": "text",
            "tooltip": null,
            "disabled": true
          },
          "AccountType": {
            "label": "SourceAccount.AccountType",
            "type": "number",
            "tooltip": null,
            "disabled": true
          }
        }
      }
    }
  }
}

where

eventTypeIdentifier - Unique event type identifier which will be also used to generate a C# class. Hence the identifier must be a valid class name. See https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/identifier-names for details
name - Human-readable name for the triggering event. Will be used by admin users to pick a triggering event.
description - detailed event description
fields - Collection of event fields along with their types. Field names should be unique for the event. Field types can be one of .NET built in types https://docs.microsoft.com/pl-pl/dotnet/csharp/language-reference/builtin-types/built-in-types or a type defined in the subTypes property
subTypes - collection of complex types used in event properties

Minimum required event scheme

The minimum required event scheme to register a custom event is passing eventTypeIdentifier and name.

POST /integration/insights/v1/events
curl --request POST '/integration/insights/v1/events' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "eventTypeIdentifier": "OnlyNamePassed",
  "name": "Event with minimal accepted scheme"
}'

Examples of faulty requests

Event identifier is not proper class name

POST /integration/insights/v1/events
curl --request POST '/integration/insights/v1/events' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "eventTypeIdentifier": "Carbon Insight Created",
  "name": "Carbon Insight",
  "description": "Event sent on carbon insight creation"
}'

400 Bad Request
{
  "errors": [
    {
      "message": "Bad Request",
      "messageDetails": null,
      "modelState": {
        "EventTypeIdentifier": [
          "EventTypeIdentifier must be a valid C# class name. 
          See: https://docs.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/identifier-names."
        ]
      }
    }
  ]
}

How this request should look like?:

POST /integration/insights/v1/events
curl --request POST '/integration/insights/v1/events' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "eventTypeIdentifier": "CarbonInsightCreated",
  "name": "Carbon Insight",
  "description": "Event sent on carbon insight creation"
}'

Field type is not supported one

POST /integration/insights/v1/events
curl --request POST '/integration/insights/v1/events' \
 -H 'accept: text/plain' \
 -H 'Authorization: Bearer {token}' \
 -H 'Content-Type: application/json' \
 -d '{
 "eventTypeIdentifier": "CarbonInsightCreated",
   "name": "Carbon Insight",
   "description": "Event sent on carbon insight creation",
   "fields": {
       "IsActive": "Boolean"
   }
}'

400 Bad Request
{
  "errors": [
  {
    "message": "Bad Request",
    "messageDetails": null,
    "modelState": {
      "": [
        "Some SubTypes used in Fields section were not declared [Boolean]. Either declare missing subtype or use one of the simple types: bool, byte, sbyte, char, string, decimal, double, float, int, uint, nint, nuint, long, ulong, short, ushort, guid, datetime, datetimeoffset, timespan, timeonly, dateonly. Nullable versions and collections (specified as Type[] for example long[]) of allowed types are also supported."
      ]
    }
  }
 ]
}

How this request should look like?

POST /integration/insights/v1/events
curl --request POST '/integration/insights/v1/events' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "eventTypeIdentifier": "CarbonInsightCreated",
    "name": "Carbon Insight",
    "description": "Event sent on carbon insight creation",
    "fields": {
        "IsActive": "bool"
    }
}'

Custom nested structure is not specified

POST /integration/insights/v1/events
curl --request POST '/integration/insights/v1/events' \
 -H 'accept: text/plain' \
 -H 'Authorization: Bearer {token}' \
 -H 'Content-Type: application/json' \
 -d '{
 "eventTypeIdentifier": "CarbonInsightCreated",
    "name": "Carbon Insight",
    "description": "Event sent on carbon insight creation",
    "fields": {
        "SourceAccount": "AccountType"
    },
   "subTypes": [
     {
       "name": "Account",
       "fields": {
         "AccountIdentifier": "string",
         "AccountType": "int"
       }
     }
   ]
}'

400 Bad Request
{
  "errors": [
  {
    "message": "Bad Request",
    "messageDetails": null,
    "modelState": {
      "": [
        "Some SubTypes used in Fields section were not declared [AccountType]. Either declare missing subtype or use one of the simple types: bool, byte, sbyte, char, string, decimal, double, float, int, uint, nint, nuint, long, ulong, short, ushort, guid, datetime, datetimeoffset, timespan, timeonly, dateonly. Nullable versions and collections (specified as Type[] for example long[]) of allowed types are also supported."
      ]
    }
  }
 ]
}

How this request should look like?:

POST /integration/insights/v1/events
curl --request POST '/integration/insights/v1/events' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "eventTypeIdentifier": "CarbonInsightCreated",
  "name": "Carbon Insight",
  "description": "Event sent on carbon insight creation",
  "fields": {
      "SourceAccount": "Account"
    },
  "subTypes": [
    {
      "name": "Account",
      "fields": {
        "AccountIdentifier": "string",
        "AccountType": "int"
      }
    }
  ]
}'

Field type is specified using C# collection types

POST /integration/insights/v1/events
curl --request POST '/integration/insights/v1/events' \
 -H 'accept: text/plain' \
 -H 'Authorization: Bearer {token}' \
 -H 'Content-Type: application/json' \
 -d '{
 "eventTypeIdentifier": "CarbonInsightCreated",
 "name": "Carbon Insight",
 "description": "Event sent on carbon insight creation",
 "fields": {
     "CategoryIds": "Array<int>",
     "MerchantIds": "List<long>",
     "Merchants": "Dictionary<long,string>"
 }
}'

400 Bad Request
{
  "errors": [
  {
    "message": "Bad Request",
    "messageDetails": null,
    "modelState": {
      "": [
        "Some SubTypes used in Fields section were not declared [Array<int>, List<long>, Dictionary<long,string>]. Either declare missing subtype or use one of the simple types: bool, byte, sbyte, char, string, decimal, double, float, int, uint, nint, nuint, long, ulong, short, ushort, guid, datetime, datetimeoffset, timespan, timeonly, dateonly. Nullable versions and collections (specified as Type[] for example long[]) of allowed types are also supported."
      ]
    }
  }
 ]
}

How this request should look like?:

POST /integration/insights/v1/events
curl --request POST '/integration/insights/v1/events' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "eventTypeIdentifier": "CarbonInsightCreated",
    "name": "Carbon Insight",
    "description": "Event sent on carbon insight creation",
    "fields": {
        "CategoryIds": "int[]",
        "MerchantIds": "long[]",
        "Merchants": "Merchant[]"
    },
    "subTypes": [
        {
            "name": "Merchant",
            "fields": {
                "Id": "long",
                "Name": "string"
            }
        }
    ]
}'

Step 2: Adding event metadata (optional)

Once an event is registered users can define new Insight Definitions in Insight Factory which will be triggered by this event.

note

At this stage users will be able to define triggering and audience conditions using the triggering event and available repository methods.

In order to use event properties in Insight Definition conditions we need to provide some event Metadata

Receiving custom events from any source

Once custom event schema is registered Insights Factory can accept incoming custom events.

Event are accepted through API endpoint:

note

Full API specification for publishing Custom Events can be found in Insights Factory Integration External Events Consumer API.

Note: Lets assume that the event schema was registered with the request

POST /integration/insights/v1/external-events-consumer/events
curl -X POST '/integration/insights/v1/external-events-consumer/events' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '  {
  "userIdentity": {
          "id": 123,
          "identifier": "2808817777",
          "tenant": "a-tenant",
          "shardingKey": "a-shard"
      },
  "eventData": [
              {
              "eventType": "Add",
              "id": "123",
              "version": 10,
              "properties": {
                  "Identifier": "some transaction identifier",
                  "ParentIdentifier": "some parent identifier",
                  "AccountIdentifier": "some account",
                  "TransactionDateTime": "2022-02-02",
                  "CarbonGrams": "29",
                  "CategoryId": "14",
                  "InsertedDate": "2022-02-01",
                  "Amount": "85.44",
                  "Currency": "EUR"
              }
          }
      ],
  "eventName": "CarbonInsightCreated"
  }'

where:

userIdentity - describes the identity of the user event relates to
- id - user id
- identifier - user identifier
- tenant - unique identifier of the tenant which the event is meant for
- shardingKey - key stating where the user's data is placed in
eventData - collection of the eventdata. Collection should contain only data of a single event type. It's not allowed to mix data from different events in a single request.
- eventType - type of event data. Possible values: [Add, Update, Delete]. Default value: Add.
- id - unique identifier of the entity that event is related to.
- version - version of the entity
- properties - properties of the event (if values are not specified default ones are assumed)
eventName - unique event name, must be the same as the eventIdentifier used during event schema registration

As it is allowed to register event scheme without properties the minimum required scope while receiving custom events are:

userIdentity properties: id, identifier, tenant, shardingKey
eventData properties: id,version
eventName

POST /integration/insights/v1/external-events-consumer/events
curl -X POST '/integration/insights/v1/external-events-consumer/events' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '  {
  "userIdentity": {
          "id": 123,
          "identifier": "2808817777",
          "tenant": "a-tenant",
          "shardingKey": "a-shard"
      },
    "eventData": [
          {
              "id": "123",
              "version": 10
          }
      ],
    "eventName": "OnlyNamePassed"
  }'

Examples of faulty event publishing requests

Passing event not registered in the system

POST /integration/insights/v1/external-events-consumer/events
curl -X POST '/integration/insights/v1/external-events-consumer/events' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "userIdentity": {
        "id": 123,
        "identifier": "2808817777",
        "tenant": "a-tenant",
        "shardingKey": "a-shard"
    },
    "eventData": [
        {
            "eventType": "Add",
            "id": "6322",
            "version": 10,
            "properties": {
                "aProperty": "test-property1",
                "bProperty": "test-property2"
            }
        }
    ],
    "eventName": "NotRegisteredEvent"
  }'

400 Bad request
{
  "errors": [
    {
      "message": "Bad Request",
      "messageDetails": null,
      "modelState": {
        "EventName": [
          "There is no event with name: 'NotRegisteredEvent' defined, please define it using BankAdmin API."
        ]
      }
    }
  ]
}

Request does not fulfill minimum required scope of data

POST /integration/insights/v1/external-events-consumer/events
curl -X POST '/integration/insights/v1/external-events-consumer/events' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "userIdentity": {
        "id": 123,
        "identifier": "2808817777",
        "tenant": "a-tenant",
        "shardingKey": "a-shard"
    },
    "eventData": [
        {
            "eventType": "Add",
            "properties": {
                "Identifier": "test-identifier"
            }
        }
    ]
  }'

400 Bad request
{
  "errors": [
    {
      "message": "Bad Request",
      "messageDetails": null,
      "modelState": {
        "EventName": [
          "'Event Name' must not be empty."
        ],
        "EventData[0].Id": [
          "'Id' must not be empty."
        ],
        "EventData[0].Version": [
          "'Version' must be greater than '0'."
        ]
      }
    }
  ]
}

Passing property not existing in registered scheme

POST /integration/insights/v1/external-events-consumer/events
curl -X POST '/integration/insights/v1/external-events-consumer/events' \
  -H 'accept: */*' \
  -H 'Authorization: Bearer {token}' \
  -H 'Content-Type: application/json' \
  -d '{
  "userIdentity": {
    "id": 123,
    "identifier": "2808817777",
    "tenant": "a-tenant",
    "shardingKey": "a-shard"
  },
  "eventData": [
    {
      "eventType": "Add",
      "id": "6322",
      "version": 10,
      "properties": {
           "Identifier": "test-identifier",
           "NotExistingProperty": 123
      }
    }
  ],
  "eventName": "CarbonInsightCreated"
}'

400 Bad request
{
  "errors": [
    {
      "message": "Bad Request",
      "messageDetails": null,
      "modelState": {
        "EventData[0]": [
          "Property 'NotExistingProperty' is not defined for the event: 'CarbonInsightCreated'"
        ]
      }
    }
  ]
}

Events registration

What is the custom event?​

How to integrate the custom event?​

Step 1: Event schema registration​

Minimum required event scheme​

Examples of faulty requests​

Step 2: Adding event metadata (optional)​

Receiving custom events from any source​

Examples of faulty event publishing requests​

What is the custom event?

How to integrate the custom event?

Step 1: Event schema registration

Minimum required event scheme

Examples of faulty requests

Step 2: Adding event metadata (optional)

Receiving custom events from any source

Examples of faulty event publishing requests